Low-level Functions21

These functions provide more complex and comprehensive interfaces to the effects dialog functionality. Using the low-level functions, you can gain more control over the standard parameters dialog box, for example allowing you to incorporate user interface elements from the dialog box into your own application-defined dialog box.

ImageCodecGetParameterList

The ImageCodecGetParameterList function returns a parameter description data structure for the specified component instance.



 
ComponentResult ImageCodecGetParameterList(

                     ComponentInstance ci,

                                         QTAtomContainer *parameterDescription);

ci: An instance of an effect component.
parameterDescription: The returned parameters description data structure for this component instance.

DESCRIPTION

This function returns the parameter description for the component instance ci . The parameter description is a set of QTAtom data structures stored inside a QTAtomContainer . Each parameter of the effect is described in the parameter description, with details of its name, type, legal values and hints about how a user interface to the parameter should be constructed.

For full details of the set of atoms stored in a parameter description, see "The Parameter Description Format" .

SPECIAL CONSIDERATIONS

The calling application is responsible for disposing of the QTAtomContainer returned in parameterDescription . The application should do this by calling QTDisposeAtomContainer once it has finished using the parameter description.

ImageCodeCreateStandardParameterDialog

This function creates a parameters dialog box for the specified effect. The dialog box allows the user to set the parameter values for the effect. You can optionally request that the controls from the dialog box be included within a dialog box of the calling application.



 
ComponentResult ImageCodecCreateStandardParameterDialog (

                                         ComponentInstance ci,

                                         QTAtomContainer parameterDescription,

                                         QTAtomContainer parameters,

                                         QTParameterDialogOptions  dialogOptions,

                                         DialogPtr existingDialog,

                                         short existingUserItem,

                                         QTParameterDialog *createdDialog);

ci: An instance of an effect component. The dialog box that is created will allow the user to specify the parameters of this effect.
parameterDescription: The parameter description for this effect. You can obtain a valid parameterDescription by calling ImageCodecGetParameterList .
parameters: The container that will receive the user's chosen parameter values once the dialog has been dismissed.
dialogOptions: Control over how parameters containing tween data are presented in the created dialog box. If dialogOptions contains 0 , two values are collected for each parameter that can be tweened, and the usual tweening operation will be performed for the duration of the effect being controlled.; If dialogOptions contains pdOptionsCollectOneValue , only one value can be entered for any parameters that can be tweened. This means that parameter values will not be tweened when the effect is played back.; If dialogOptions contains pdOptionsAllowOptionalInterpolations , parameters that are defined as kAtomInterpolateIsOptional in their parameter description will be allowed to take tweened values. This allows you to force the "advanced" user interface mode described in "Parameter Atom Type and ID" .
existingDialog: An existing dialog box that will have the controls from the standard parameters dialog box added to it. This parameter may contain nil if you want ImageCodecCreateStandardParameterDialog to create a stand-alone dialog box. If existingDialog is not nil , the controls that would make up the dialog box are instead added to the existing dialog box.
existingUserItem: The number of the user item in the existing dialog box that should be replaced with controls from the standard parameter dialog box. You should only pass a value to this parameter if the existingDialog parameter is not nil .
createdDialog: On exit, this parameter contains a reference to the dialog created and displayed by the function. This reference is required by several other low-level effects functions. It will contain a valid dialog identifier even if you requested that the controls from the standard parameter dialog box are incorporated into an existing dialog box.

DESCRIPTION

This function can to create a stand-alone standard parameter dialog box, or it can add the controls from the standard parameter dialog box to an existing dialog box provided by the calling application.

ImageCodecIsStandardParameterDialogEvent

This function processes events related to a standard parameters dialog box.



 
ComponentResult ImageCodecIsStandardParameterDialogEvent(

                                         ComponentInstance ci,

                                         EventRecord *pEvent,

                                         QTParameterDialog createdDialog);

ci: An instance of an effect component. This must be the instance that was passed to ImageCodecCreateStandardParameterDialog to create the dialog box.
pEvent: A pointer to an event record returned by WaitNextEvent .
createdDialog: A reference to the dialog box created by the call to ImageCodecCreateStandardParameterDialog .

DESCRIPTION

After you call ImageCodecCreateStandardParameterDialog to create a standard parameter dialog box, you must pass every non-null event return from WaitNextEvent to ImageCodecIsStandardParameterDialogEvent . The function processes events related to the standard parameter dialog box, passing other events to your application for processing.

ImageCodecIsStandardParameterDialogEvent returns an error code that indicates whether the event pointed to by pEvent was processed or not. If the error code returned is featureUnsupported , your application should process the event in the normal way. If the ImageCodecIsStandardParameterDialogEvent returns any other value, the event was processed or an error occurred.

RESULT CODES

`featureUnsupported`	The event was not processed by the function. Your application should process the event normally.
`codecParameterDialogConfirm`	The user clicked the OK button in the dialog box. Your application should call `ImageCodecStandardParameterDialogDoAction` , then `ImageCodecDismissStandardParameterDialog.`
`userCanceledErr`	The user clicked the Cancel button in the dialog box. Your application should call `ImageCodecDismissStandardParameterDialog.`

ImageCodecStandardParameterDialogDoAction

This function allows you to retrieve values from a standard parameter dialog box. You should only call this function if you incorporated the user interface elements of the standard parameter dialog box into your own dialog box. If you created a stand-alone standard parameters dialog box, this function is automatically called for you when the user clicks the OK button.



 
ComponentResult ImageCodecStandardParameterDialogDoAction( 

                                         ComponentInstance ci,

                                         QTParameterDialog createdDialog,

                                         long action,

                                         void *params);

ci: An instance of an effect component. This must be the same instance as was passed to ImageCodecCreateStandardParameterDialog to create the dialog box.
createdDialog: A reference to the dialog box created by the call to ImageCodecCreateStandardParameterDialog .
action: The action selector, which determines which of the available actions you want the function to perform.
params: The (optional) parameter to the action. The type passed in this parameter depends on the value of the action parameter.

DESCRIPTION

The ImageCodecStandardParameterDialogDoAction function allows you to change the default behavior of the standard parameter dialog box, and provides a mechanism for your application to communicate with controls that were incorporated into an application dialog box. It also allows you to retrieve parameter values from the dialog box at any time.

You specify which function will be performed by passing an action selector in the action parameter and, optionally, a single parameter in params .

The following list describes the available action selectors:

pdActionSetDialogTitle: Sets the title of the standard parameters dialog box from the params parameter, which contains a Pascal Str255 string.
pdActionConfirmDialog: Retrieves the current parameter values from the standard parameters dialog box. The parameter values are placed in the parameters parameter that was passed to the appropriate call to ImageCodecCreateStandardParameterDialog .
pdActionSetAppleMenu: Use this selector to make the Apple menu available while the standard parameter dialog box is active. Pass the MenuHandle of the Apple menu in the params parameter.
pdActionSetEditMenu: Use this action to make your application's Edit menu available while the standard parameters dialog box is active.Pass the MenuHandle of the Edit menu in the params parameter.
pdActionGetDialogValues: Retrieves the current parameter values from the standard parameters dialog box. The parameter values are placed in the QTAtomContainer you pass in the params parameter to this call.
pdActionSetPreviewUserItem: Passes the number of the user item that should be replaced by the effect preview movie clip. The params parameter contains a long integer holding the user item number.
pdActionSetPreviewPicture: Use this action to change the images that are used in the preview window of the standard parameters dialog box. QuickTime provides default images but you may wish, for example, to use thumbnail images taken from your application instead. The params parameter contains a QTParamPreviewPtr referencing the image to use (see "Parameter Dialog Box Preview Image Specifier" ).
pdActionSetColorPickerEventProc: Set the function that will be used when the standard parameters dialog box needs to display a color picker. The params parameter should contain a UserEventUPP that points to the replacement color picker function.
pdActionSetDialogTitle: Sets the title of the standard parameters dialog box. The params parameters should contain a Pascal Str255 string.
pdActionGetSubPanelMenu: Returns a list of the sub-panels used by the standard parameters dialog box. If there are more parameter controls than can fit into the available area of the dialog box, the parameters are automatically split into sub-panels (usually by segmenting the set of parameters by group). The pop-up menu used to switch between the panels is returned as a MenuHandle in the params parameter.
pdActionActivateSubPanel: Sets the current sub-panel. The params parameter contains a long integer that is the number of the panel to be displayed.
pdActionConductStopAlert

ImageCodecDismissStandardParameterDialog

This function retrieves values from a standard parameter dialog box, then closes the dialog box.



 
ComponentResult ImageCodecDismissStandardParameterDialog(

                                         ComponentInstance ci, 

                                         QTParameterDialog createdDialog);

ci: An instance of an effect component. This must be the same instance as was passed to ImageCodecCreateStandardParameterDialog to create the dialog box.
createdDialog: A reference to the dialog box created by the call to ImageCodecCreateStandardParameterDialog .

DESCRIPTION

This function should be called after the ImageCodecIsStandardParameterDialogEvent function returns codecParameterDialogConfirm or userCanceledErr , which indicate that the user has dismissed the dialog box.

The function dismisses the dialog box, deallocating any memory allocated during the call to the ImageCodecCreateStandardParameterDialog function.